home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / cpp_libs / cool / ge_cool.lha / GE_COOL2.1 / man / oldman3 / String.3T < prev    next >
Text File  |  1992-06-26  |  17KB  |  514 lines
  1. .TH STRING 
  2. .SH NAME
  3. String  Simple, dynamic string class
  4. .SH SYNOPSIS
  5. #include <cool/String.h>
  6. .SH DESCRIPTION
  7. The String\f1 class provides dynamic, efficient strings for a
  8. C++ application. The 
  9. intent is to provide efficient \f3char*\f1-like functionality that frees the 
  10. programmer from worrying about memory allocation and deallocation problems, yet 
  11. retains the speed and compactness of a standard \f3char*\f1 implementation. The 
  12. \f3String\f1 class is dynamic in the sense that if an operation such as concatenate results in more characters than can fit in the currently allocated memory, the string object \f2grows\f1 according to some established size or ratio value. All typical string operations are provided, including concatenation, case-sensitive and case-insensitive lexical comparison, string search, yank, delete, and 
  13. replacement. System-provided functions for \f3char*\f1 such as \f3strcpy\f1 and \f3strcmp\f1 are also available via the overloaded \f3operator char* \f1 member function.
  14. .SH Base Classes
  15.  
  16. .SH Friend Classes
  17. None
  18. .SH Constructors
  19. .TP
  20.  String ();
  21. Initializes an empty string object with a default size block of memory 
  22. allocated to hold 100 characters.
  23. .TP
  24. \f3String (char \f2c\f3);\f1
  25. Initializes a string object with the default size block of memory allocated to 
  26. hold 100 characters whose value is the string consisting of the single 
  27. character argument \f2c\f1.
  28. .TP
  29. \f3String (const char* \f2str\f3);\f1
  30. Initializes a string object with the default size block of memory allocated to 
  31. hold 100 characters whose value is copied from the specified character string 
  32. argument 
  33.  str .  
  34. If \f2str\f1 is longer, the string will grow as necessary.
  35. .TP
  36. \f3String (const char* \f2str\f3, long \f2size\f3);\f1
  37. Allocates an initial block of memory the size of the integer argument \f2size\f1, or 
  38. the s\f3trlen(\f2str\f3)\f1, whichever is longer. and initializes the string object with a copy of the specified character string \f2str\f1. Note that \f2size\f1 is ignored if less than the length of \f2str\f1.
  39. .TP
  40. \f3String (const String& \f2str\f3);\f1
  41. Duplicates the size and value of another string object \f2str\f1.
  42. .TP
  43. \f3String (const String& \f2str\f3, long \f2size)\f3;\f1
  44. Duplicates the size and value of another string object \f2str\f1 by allocating an 
  45. initial block of memory to be the size of the integer argument \f2size\f1, or 
  46. \f3strlen(\f2str\f3)\f1, whichever is longer. The duplication is then performed.
  47. .SH Member Functions
  48. .TP
  49.  inline long capacity () const;
  50. Returns the maximum number of characters that the string object can contain 
  51. without having to grow.
  52. .TP
  53.  void clear ();
  54. Resets the 
  55.  
  56.  NULL
  57. character string terminator to the beginning of the string and 
  58. sets the length of the string to zero.
  59.  
  60. .TP
  61. \f3Boolean insert (const char* \f2str\f3, long \f2position\f3);\f1
  62. Inserts a copy of the sequence of characters pointed to by the first argument 
  63. \f2str\f1 at the zero-relative index provided by the second argument \f2position\f1. This function returns 
  64.  
  65.  TRUE
  66. if successful; otherwise, this function returns 
  67.  
  68.  FALSE
  69. if the index is out of range.
  70. .TP
  71.  inline operator char* () const;
  72. Provides an implicit conversion operator to convert a string object into a 
  73. \f3char*\f1 value.
  74. .TP
  75. \f3String operator+ (char \f2c\f3);\f1
  76. Overloads the addition operator to concatenate a single character \f2c\f1 to a string object. This function returns a new string object, via the stack.
  77. .TP
  78. \f3String operator+ (const char* \f2str\f3);\f1
  79. Overloads the addition operator to concatenate a copy of the specified 
  80. character sequence \f2str\f1 to a string object. This function returns a new string object.
  81. .TP
  82. \f3String operator+ (const String& \f2str\f3);\f1
  83. Overloads the addition operator to concatenate the value of the specified 
  84. string object \f2str\f1 to a string object. This function returns a new string 
  85. object. 
  86. .TP
  87. \f3inline String& operator= (char \f2c\f3);\f1
  88. Overloads the assignment operator to assign a single character \f2c\f1 to a string object. This function returns a reference to the modified string object.
  89. .TP
  90. \f3inline String& operator= (const char* \f2str\f3);\f1
  91. Overloads the assignment operator to assign a copy of the specified character 
  92. sequence \f2str\f1 to a string object.  This function returns a reference to themodified string object.
  93. .TP
  94. \f3inline String& operator= (const String& \f2str\f3);\f1
  95. Overloads the assignment operator to assign the value of another string object 
  96. \f2str\f1 to a string object. This function returns a reference to the modified 
  97. string object.
  98. .TP
  99. \f3inline String& operator+= (char \f2c\f3);\f1
  100. Overloads the addition-and-assignment operator to concatenate a
  101. single character 
  102.  c
  103. to a string object.
  104. This function returns a reference to the modified string object. 
  105. .TP
  106. \f3inline String& operator+= (const char* \f2str\f3);\f1
  107. Overloads the addition-and-assignment operator to concatenate a copy of the
  108. specified character sequence \f2str\f1 to a string object. 
  109. This function returns a reference to the modified string object.
  110. .TP
  111. \f3inline String& operator+= (const String& \f2str\f3);\f1
  112. Overloads the addition-and-assignment operator to concatenate the value of the 
  113. specified string object \f2str\f1 to a string object. This function returns a 
  114. reference to the modified string object.
  115. .TP
  116. \f3inline Boolean operator== (const char* \f2str\f3) const;\f1
  117. Overloads the equality operator for the 
  118.  String 
  119. class. This function returns 
  120.  
  121.  TRUE 
  122. if the string object and 
  123.  str 
  124. have the same sequence of characters; 
  125. otherwise, this function returns 
  126.  
  127.  FALSE .  
  128. .TP
  129. \f3inline Boolean operator== (const String& \f2str\f3) const;\f1
  130. Overloads the equality operator for the \f3String\f1 class. This function returns 
  131.  
  132.  TRUE
  133. if the strings have the same sequence of characters; otherwise, this function returns 
  134.  
  135.  FALSE .
  136. .TP
  137. \f3inline Boolean operator!= (const char* \f2str\f3) const;\f1
  138. Overloads the inequality operator for the \f3String\f1 class. This function returns 
  139.  
  140.  FALSE
  141. if the string object and \f2str\f1 have the same sequence of characters; otherwise, this function returns 
  142.  
  143.  TRUE .
  144. .TP
  145. \f3inline Boolean operator!= (const String& \f2str\f3) const;\f1
  146. Overloads the inequality operator for the \f3String\f1 class. This function returns 
  147.  
  148.  FALSE
  149. if the strings have the same sequence of characters; otherwise, this function returns 
  150.  
  151.  TRUE .
  152. .TP
  153. \f3inline Boolean operator< (const char* \f2str\f3) const;\f1
  154. Overloads the less-than operator for the \f3String\f1 class. This function returns 
  155.  
  156.  TRUE
  157. if the string is lexically less than the \f2char* s\f1 argument; otherwise, this function returns 
  158.  
  159.  FALSE .
  160. .TP
  161. \f3inline Boolean operator< (const String& \f2str\f3) const;\f1
  162. Overloads the less-than operator for the \f3String\f1 class. This function returns 
  163.  
  164.  TRUE 
  165. if the string object is lexically less than the string \f2str\f1\^; otherwise, 
  166. this function returns
  167.  
  168.  FALSE .
  169. .TP
  170. \f3inline Boolean operator<= (const char* \f2str\f3) const;\f1
  171. Overloads the less-than-or-equal operator for the \f3String\f1 class. This function returns 
  172.  
  173.  TRUE 
  174. if the string object is lexically less than or equal to the 
  175. character string argument \f2str\f1\^; otherwise, this function returns
  176.  
  177.  FALSE . 
  178. .TP
  179. \f3inline Boolean operator<= (const String& \f2str\f3) const;\f1
  180. Overloads the less-than-or-equal operator for the \f3String\f1 class. This function returns
  181.  
  182.  TRUE
  183. if the string object is lexically less than or equal to the string \f2str\f1\^;
  184. otherwise, this function returns
  185.  
  186.  FALSE .  
  187. .TP
  188. \f3inline Boolean operator> (const char* \f2str\f3) const;\f1
  189. Overloads the greater-than operator for the \f3String\f1 class. This function returns 
  190.  
  191.  TRUE
  192. if the string object is lexically greater than the character string 
  193. argument \f2str\f1\^; otherwise, this function returns 
  194.  
  195.  FALSE . 
  196. .TP
  197. \f3inline Boolean operator> (const String& \f2str\f3) const;\f1
  198. Overloads the greater-than operator for the
  199.  String
  200. class. This function returns 
  201.  
  202.  TRUE
  203. if the string object is lexically greater than the string 
  204.  str ; 
  205. otherwise, 
  206. this function returns 
  207.  
  208.  FALSE .
  209. .TP
  210. \f3inline Boolean operator>= (const char* \f2str\f3) const;\f1
  211. Overloads the greater-than-or-equal operator for the 
  212.  String
  213. class. This function returns 
  214.  
  215.  TRUE 
  216. if the string object is lexically greater than or equal 
  217. to the character string argument
  218.  str ; 
  219. otherwise, this function returns
  220.  
  221.  FALSE .   
  222. .TP
  223. \f3inline Boolean operator>= (const String& \f2str\f3) const;\f1
  224. Overloads the greater-than-or-equal operator for the 
  225.  String 
  226. class. This function returns 
  227.  
  228.  TRUE 
  229. if the string object is lexically greater than or equal 
  230. to the string 
  231.  str ; 
  232. otherwise, this function returns 
  233.  
  234.  FALSE .  
  235. .TP
  236. \f3inline char operator[] (long \f2position\f3) const;\f1
  237. Returns the character at the zero-relative index 
  238.  position 
  239. in the string. If the index is invalid, an \f3\f3Error\f1\f1 exception is raised.
  240. .TP
  241. \f3Boolean remove (long \f2start\f3, long \f2end\f3);\f1
  242. Removes the sequence of characters between the zero-relative inclusive 
  243.  start 
  244. and exclusive
  245.  end 
  246. indexes. This function returns 
  247.  
  248.  TRUE 
  249. if successful; otherwise, this function returns 
  250.  
  251.  FALSE 
  252. if either one or both of the indexes is out of range.
  253. .TP
  254. \f3Boolean replace (const char* \f2str\f3, long \f2start\f3, long \f2end\f3);\f1
  255. Replaces the sequence of characters between the zero-relative inclusive 
  256.  start 
  257. and exclusive 
  258.  end
  259. indexes with a copy of the character string 
  260.  str . 
  261. This function returns 
  262.  
  263.  TRUE 
  264. if successful; otherwise, this function returns 
  265.  
  266.  FALSE 
  267. if either one or both of the indexes is out of range.
  268. .TP
  269. \f3void resize (long \f2size\f3);\f1
  270. Resizes the string object to hold at least 
  271.  size 
  272. number of characters.  If 
  273.  size 
  274. is less than existing length, the operation is ignored.
  275. .TP
  276.  void reverse ();
  277. Reverses the ordering of the characters in a string object.
  278. .TP
  279. \f3inline void set_alloc_size (int \f2size\f3);\f1
  280. Updates the allocation growth size to be used when the growth ratio is zero. 
  281. Default allocation growth size is 100 bytes. If 
  282.  size 
  283. is negative, an \f3\f3Error\f1\f1 exception is raised.
  284. .TP
  285. \f3inline void set_growth_ratio (float \f2ratio\f3);\f1
  286. Updates the growth ratio for this instance of a string to the specified value. 
  287. When a string needs to grow, the current size is multiplied by  the ratio to 
  288. determine the new size. If 
  289.  ratio 
  290. is negative, an 
  291.  \f3\f3Error\f1\f1 
  292. exception is raised.
  293. .TP
  294. \f3void sub_string (String& \f2str\f3, long \f2start\f3, long \f2end\f3);\f1
  295. Sets the given string object 
  296.  str 
  297. to the values in the character sequence between the zero-relative inclusive 
  298.  start 
  299. and exclusive 
  300.  end
  301. indexes provided. 
  302. This function returns 
  303.  
  304.  TRUE 
  305. if successful; otherwise, this function returns 
  306.  
  307.  FALSE 
  308. if either one or both of the indexes is out of range.
  309. .TP
  310. \f3void yank (String& \f2str\f3, long \f2start\f3, long \f2end\f3);\f1
  311. Deletes the sequence of characters between the zero-relative inclusive 
  312.  start 
  313. and exclusive 
  314.  end 
  315. indexes provided and sets the given string object 
  316.  str 
  317. to the value of the deleted characters.
  318. .SH Friend Functions
  319. .TP
  320. \f3inline friend double atof (const String& \f2str\f3);\f1
  321. Returns the floating-point value represented by the characters in the string 
  322. object 
  323.  str .  
  324. .TP
  325. \f3friend int atoi (const String& \f2str\f3);\f1
  326. Returns the decimal radix integer number represented by the characters in the 
  327. string object 
  328.  str .
  329. .TP
  330. \f3friend long atol (const String& \f2str\f3);\f1
  331. Returns the decimal radix long number represented by the characters in the 
  332. string object 
  333.  str .
  334. .TP
  335. \f3friend String& capitalize (String& \f2str\f3);\f1
  336. Capitalizes each word and returns the modified string 
  337.  str . 
  338. A word is defined to be any subsequence of alphanumeric characters. 
  339. This function returns a reference to the modified string 
  340.  str .
  341. .TP
  342. \f3friend String& downcase (String& \f2str\f3);\f1
  343. Converts any alphabetic character to lowercase. This function returns a 
  344. reference to the modified string 
  345.  str .
  346. .TP
  347. \f3friend String& left_trim (String& \f2str1\f3, const char* \f2str2\f3);\f1
  348. Removes any prefix occurrence of the character string 
  349.  str2 
  350. specified from the string object 
  351.  str1 . 
  352. This function returns a reference to the modified string 
  353.  str1 .
  354. .TP
  355. \f3friend ostream& operator<< (ostream& \f2os\f3, const String& \f2str\f3);\f1
  356. Overloads the output operator for a reference to a string object 
  357.  str .
  358. .TP
  359. \f3inline friend ostream& operator<< (ostream& \f2os\f3, const String* \f2str\f3);\f1
  360. Overloads the output operator for a pointer to a string object 
  361.  str .
  362. .TP
  363. \f3friend String& right_trim (String& \f2str1\f3, const char* \f2str2\f3);\f1
  364. Removes any suffix occurrence of the character string 
  365.  str2 
  366. specified from the 
  367. string object 
  368.  str1 . 
  369. This function returns a reference to the modified string 
  370.  str2 .
  371. .TP
  372. \f3friend String& strcat (String& \f2str\f3, char \f2c\f3);\f1
  373. Returns the result of concatenating the character 
  374.  c 
  375. to a string object 
  376.  str .
  377. .TP
  378. \f3friend String& strcat (String& \f2str1\f3, const char* \f2str2\f3);\f1
  379. Returns the result of concatenating a copy of the specified character string 
  380.  str2 
  381. to a string object 
  382.  str1 .
  383. .TP
  384. \f3friend String& strcat (String& \f2str1\f3, const String& \f2str2\f3);\f1
  385. Returns the result of concatenating one string object 
  386.  str2 
  387. to another 
  388.  str1 . 
  389. This function returns the modified string object 
  390.  str1. 
  391. .TP
  392. \f3friend char* strchr (const String& \f2str\f3, char \f2c\f3);\f1
  393. Overloads the forward character search function to scan from left to right 
  394. through a string object 
  395.  str 
  396. for the first occurrence of the character 
  397.  c . 
  398. This function returns a pointer to the character if found; otherwise, this function returns 
  399.  
  400.  NULL .
  401. .TP
  402. \f3friend String& strcpy (String& \f2str1\f3, char \f2str2\f3);\f1
  403. Overloads the copy string function to copy the character string 
  404.  str2 
  405. into a string argument 
  406.  str1 . 
  407. This function returns a reference to the modified string 
  408. object 
  409.  str1 .       
  410. .TP
  411. \f3friend String& strcpy (String& \f2str1\f3, const char* \f2str2\f3);\f1
  412. Overloads the copy string function to copy the specified character string 
  413.  str2 
  414. argument into the string argument 
  415.  str1 . 
  416. This function returns a reference to the modified string object 
  417.  str1 .
  418. .TP
  419. \f3friend String& strcpy (String& \f2str1\f3, const String& \f2str2\f3);\f1
  420. Overloads the copy string function to copy the second string argument 
  421.  str2 
  422. into the first string argument 
  423.  str1 . 
  424. This function returns the modified string 
  425. object 
  426.  str1 .
  427. .TP
  428. \f3inline friend long strlen (const String& \f2str\f3);\f1
  429. Returns the number of characters (length) of the string 
  430.  str .
  431. .TP
  432. \f3friend String& strncat (String& \f2str1\f3, const char* \f2str2\f3, int \f2length\f3);\f1
  433. Returns the result of concatenating a copy of some number of characters 
  434.  length 
  435. from a character string 
  436.  str2 
  437. to a string object 
  438.  str1 . 
  439. This function returns a reference to the modified string object 
  440.  str1 .
  441. .TP
  442. \f3friend String& strncat (String& \f2str1\f3, const String& \f2str2\f3, int \f2length\f3);\f1
  443. Returns the result of concatenating some number of characters 
  444.  length 
  445. from one string object 
  446.  str2 
  447. to another 
  448.  str1 . 
  449. This function returns a reference to the modified string object 
  450.  str1 .
  451. .TP
  452. \f3friend String& strncpy (String& \f2str1\f3, const char* \f2str2\f3, long \f2length\f3);\f1
  453. Overloads the 
  454.  strncpy 
  455. function to copy some number of characters 
  456.  length 
  457. from the specified character string argument 
  458.  str2 
  459. into the string argument 
  460.  str1 . 
  461. This function returns a reference to the modified string object 
  462.  str1 .
  463. .TP
  464. \f3friend char* strrchr (const String& \f2str\f3, char \f2c\f3);\f1
  465. Overloads the backward character search function to scan from right to left 
  466. through a string object 
  467.  str 
  468. for the last occurrence of a specific character 
  469.  c . 
  470. This function returns a pointer to the character if found; otherwise, this 
  471. function returns 
  472.  
  473.  NULL .
  474. .TP
  475. \f3friend double strtod (const String& \f2str\f3, char** \f2ptr \f3= \f3 NULL);
  476. Returns the double floating-point value represented by the characters in the 
  477. string object 
  478.  str . 
  479. If the second argument is non-zero, it is set to the 
  480. character terminating the converted string value.
  481. .TP
  482. \f3friend long strtol (const String& \f2str\f3, char** \f2ptr\f3 =  \f3NULL\f3, int \f2radix\f1=10\f3);\f1
  483. Returns the long number represented by the characters in the string object 
  484.  str . 
  485. If a specific radix is not specified, the default radix is decimal. If the 
  486. second argument is non-zero, it is set to the character terminating the 
  487. converted string value.
  488.  
  489. .TP
  490. \f3friend String& trim (String& \f2str1\f3, const char* \f2str2\f3);\f1
  491. Removes any occurrence of the character string 
  492.  str2 
  493. from the string object 
  494.  str1 . 
  495. This function returns a reference to the modified string 
  496.  str1 .
  497. .TP
  498. \f3friend String& upcase (\f2S\f3tring& \f2str\f3);\f1
  499. Converts any alphabetic character to uppercase. This function returns a 
  500. reference to the modified string 
  501.  str .
  502. .SH COPYRIGHT
  503.  
  504. Copyright (C) 1991 Texas Instruments Incorporated.
  505.  
  506. Permission is granted to any individual or institution to use, copy, modify,
  507. and distribute this software, provided that this complete copyright and
  508. permission notice is maintained, intact, in all copies and supporting
  509. documentation.
  510.  
  511. Texas Instruments Incorporated provides this software "as is" without
  512. express or implied warranty.
  513.  
  514.